"""
认证模块 - 令牌增强器接口
"""
from abc import ABC, abstractmethod
from typing import Dict

from axiom_boot.auth.models import Principal


class TokenEnhancer(ABC):
    """
    令牌增强器服务的抽象基类 (SPI - 服务提供者接口)。

    应用开发者可以实现此接口，并将其注册为一个 `@service`，
    以便在颁发 JWT 令牌时，向其载荷 (payload) 中添加额外的自定义声明。

    这对于将额外的、非敏感的业务数据（如会员等级、用户偏好等）
    嵌入到令牌中非常有用，可以减少后续请求中对数据库的查询。
    """

    @abstractmethod
    async def enhance(self, claims: Dict, principal: Principal) -> Dict:
        """
        对即将编码为 JWT 的声明进行增强。

        Args:
            claims: 框架已经生成的基础声明字典。
            principal: 当前通过认证的用户主体对象，包含了用户的核心信息。

        Returns:
            经过修改或扩充后的声明字典。
        """
        raise NotImplementedError 